Contents -turn page- Reference List Introduction

Contents | Start

Introduction

1. Introduction
1.1 1.2 1.3 1.4 1.5 1.6	Introduction System Requirements Copyright Hotline, Reporting Errors and Bugs ... The Manual The Library
Reference List Introduction

1.1 Introduction You are familiar with the Apple Finder, the program with the desktop, which appears after booting your computer; you know the drive symbols, the program icons, the menu bar, and the trash bin. You can open windows in the Finder (e.g., by double clicking on one of the drive symbols), move these windows, or enlarge and close them. By clicking on menu items, you can modify, for example, the display of the window content. Printer settings can be changed easily in a dialog box. These are just some of the many things you can do. This type of program control is considered to be a "Graphics Environment Management".

Now it is possible to equip your own programs with such an user interface utilizing the easily applied EasyGem Library and without getting lost in the depths of the Macintosh operating system. Menus, dialog boxes, and windows are simply defined and managed by using commands in your BASIC program. Therefore, you do not need a resource editor. In addition, EasyGem relieves you of most of the management and control tasks such as e.g., processing of menu events, moving window contents, and display and evaluation and interpretation of dialog boxes. However, at this point it should be mentioned that the simplification of the program also comes with a few strings attached, namely limitations. Thus, not everything that is possible on the Mac can also be realized with EasyGem. The program EasyPaint.BAS in the DEMO folder proves, however, that some quite impressive results can be achieved with very little programming efforts. Soon, advanced programmers will have EasyGem Pro at their disposal, which lets programmers get the most out of their Macs; however, this also entails that one has to become more closely acquainted with the subject matter at hand.

Note: The sentence punctuation does not adhere to the official orthographical rules of American English in order avoid copying extra punctuations marks when copying code directly from the on-line manual.

The Demo Version If you have obtained a demo version, you have access to all features and there is no temporal limitation but the following restrictions apply: Only 1 menu bar can be defined and this menu bar can contain maximal 3 menus. The number of entries per menu is limited to 10. At most 3 dialog boxes are possible which each consist of less than 15 lines. Maximal 3 windows can be open simultanously. The EasyGem Library will issue a message in intervals of 10 minutes, which will indicate that the Library in use is a demo version. In addition, programs generated with the demo version may not be sold.

1.2 System Requirements You need Omikron Basic 6 and an Apple computer with a PowerPC processor in order to be able to use EasyGem. In addition, at least 4 MB memory should be available as well: the more, the better. Since the fields of the EasyGem Library are dimensioned and require memory in the string heap (this is especially true when using text windows), you have to use the control word COMPILER "BASMEM X" to allocate and set aside sufficient BASIC memory (also consult the Omikron Basic manual regarding compiler control words and memory management). If you are working with graphic windows, you also have to reserve sufficient memory for the application heap (COMPILER "MIN_SIZE X"), because the graphics windows are buffered in that location. In principle, it is possible to run the Omikron Basic output windows parallel with the EasyGem windows. However, if at all possible, this option should be avoided because the checks and balances and control options are much more comprehensive for the EasyGem windows, and EasyGem commands have no effect on the output windows of Omikron Basic. Nevertheless, if you wish to use both windows at the same time, for example, to use the command INPUT (this command functions only on the desktop or in the Omikron Basic output windows), you need to make sure that anytime an Omikron Basic output window is at the top, the menu accompanying the Omikron Basic output window is displayed as well, and that the EasyGem menu is displayed anytime an EasyGem windows is at the top. How to accomplish this is explained in M_Show in the Menu Library.

1.3 Copyright You may copy the EasyGem Library for your own use as often as you wish. You may transfer it to your hard drive or to each work disk. However, since you are responsible for any and all illegal copies that might have been obtained from your copies, please make sure third parties do not have access to your original copies. In case you would like to pass on programs that require the EasyGem Library, you have to protect the Library against misuse by third parties. It is best to pass on only compiled programs, since it is impossible to reconstruct either the source code of your program or the Library itself from a compiled program.

1.4 Hotline, Reporting Errors/Bugs and Making Improvement Suggestions Should you still have questions or have discovered any errors or bugs in the EasyGem Library or in case you might have some suggestions for improving the program, please just contact us at one of the following addresses: E-Mail: Berkiber@T-Online.de Fax: + 49 (5832) 6160 Hotline: + 49 (5832) 979895 (Mondays to Saturdays from 12.00 noon to 1 pm, Sundays from 2 pm to 3 pm UTC ) or via postal mail to: Berkhan-Software Entwicklung & Vertrieb Alt-Isenhagen 19 D-29386 Hankensbuettel Germany

1.5 The Manual The individual functions of the EasyGem Library are not alphabetized but are rather explained sorted according to the subject field. This is meant to facilitate a step-by-step familiarization process with the subject matter at hand. An alphabetical listing of all commands discussed in the chapter can be found at the end of each chapter together with a direct link to the corresponding text passage. The syntax descriptions follow the layout of the Omikron Basic manual. EasyGem commands are depicted using the font Courier. In those cases, the actual command is in bold and the parameter normal. Text displayed in [square brackets] may be omitted.

For example:

Win_Domessages Parameter1$[,Parameter2]

This procedure offers two different possibilities for use.
The first would look within the program like this:

Win_Domessages Buf$

The second might be as follows:

Win_Domessages Buf$,&FN Close_Action(0)

The angle brackets, which are used in the Omikron Basic manual to indicate that a meaningful substitution should be inserted, are omitted here in their entirety. The parameters (normal font) are always used to indicate examples. Subsequently, you can also use other names for these. However, it is not possible to choose another name for procedure and function names (bold font), respectively. If a parameter is preceded by an "R ", it indicates that you are dealing with a return parameter. EasyGem will return a value to you at this location:

M_Waitmesag R Entry

The variable Entry will return the indicated value. Caution: The "R" may not be inserted by the programmer him- or herself. Its only purpose is to describe the syntax. The examples in these instructions presume that programming will be without line numbers. In order to try out these examples, it is best to copy them from the online manual to the clipboard and from there to an Omikron Basic window of the editor. Copying by hand is tiring and the likelihood of making typing mistakes is great.

1.6 The Library The EasyGem Library is deposited in a special encoding procedure (token code), which enables Omikron Basic to load the Library very speedily. This is done by using the menu item 'Edit/Merge LIBRARY... ' in the editor. The Library will be automatically appended to the end of your program. There, it is visible as:

LIBRARY CODE Easygem 'Version X.YZ, TT.MM.JJJJ

The line containing the LIBRARY CODE cannot be changed. At most, you can delete the line ([Alt] + [Delete]). This removes the Library from your program. After that, it is advisable to click on 'Program/Clean Sweep' in the editor so that all now superfluous EasyGem variables are removed from the table. The EasyGem Library has to be initialized/attached when the program initially starts and de-initialized/unmounted once the program is terminated. The following two calls serve this purpose:

Easy_Init

Initializes/Attaches Library.

Easy_Exit

Loggs off of/exits/unmounts Library.

This routines are executing comprehensive initialization tasks, which are essential for the actual work with EasyGem.

The skeleton of an EasyGem program appears as follows:

Easy_Init ... 'Here will be your EasyGem program ... Easy_Exit END

The skeleton as depicted above is already a runable program, which, however, has no purpose and ends again right away. Note: All those program examples of the following chapters that begin with Easy_Init and end with Easy_Exit are immediately functional and can be executed. Thus, they can be copied with 'Copy' and subsequently pasted into a program window using 'Paste.' Of course, this has to be followed with the loading of the EasyGem Library using 'Merge LIBRARY ...'. If the examples are not accompanied by Easy_Init at the beginning, you are then dealing with program fragments, whose only purpose is to explain special commands. When called, Easy_Init dimensions a few fields, which are essential for the management of the menus, dialog boxes, and windows. The size of these fields determines, e.g., how many menus, dialog boxes, windows, etc. can be used simultaneously. The preset default values are as follows:

Max_Menus = 24

Number of menus, which can be managed simultaneously.

Max_Menu_Title = 24

Number of titles within a menu.

Max_Menu_Items = 32

Number of entries under one menu title.

Max_Menu_Entry = 256

Number of entries of a menu (all titles and entries of one menu combined).

Max_Dialogs = 24

Number of dialog boxes, which can be managed simultaneously.

Max_Dialog_Lines = 32

Number of lines within a dialog box.

Max_Dialog_Objects = 16

Number of objects within one line.

Max_Dialog_Entries = 256

Combined total of all objects in all lines of a dialog box.

Max_Windows = 64

Number of windows, which can be open simultaneously.

Max_Textlines = 5000

Number of text lines, which are available for all text windows combined.

These settings should suffice completely for most cases. But you may also modify these values (e.g., reducing to save BASIC memory or increasing because you need many more windows than usual or because you want to process very long texts). In that case, replace the command Easy_Init at the beginning of your program with the following command:

Easy_Init Max_Menus, Max_Menu_Title, Max_Menu_Items, Max_Menu_Entry, Max_Dialogs, Max_Dialog_Lines, Max_Dialog_Objects, Max_Dialog_Entries, Max_Windows, Max_Textlines

And finally, this introduction would not be complete without mentioning the procedure EasyGem:

Easy_Gem

Displays copyright message.

An alert box is displayed containing the EasyGem copyright message.

Contents -turn page- Reference List Introduction

Contents | Start

© 1998-1999 Berkhan-Software www.berkhan.com | Home